Node / ReticulumProjects / MeshChatX.git / files / docs / agents / conventions / path-jail.md

Displaying Rendered • View raw • Download

Applies when adding or changing HTTP or handler code that lists, reads, writes, uploads, downloads, or deletes files under identity storage or a feature root.

Treat MeshChatX local API access (UI session, shared host, scripted client) as already compromised for the purpose of path checks. The attacker must still fail to:

• Escape the feature root with T383838../, absolute paths, null bytes, or Windows separators

• Reach sibling identity storage or host paths outside the active identity

• Touch reserved tops (T383838identity, T383838lxmf, T383838database.db, bots, plugins, backups, keys)

• Follow symlinks that point outside the jail

• Exfil via download or content endpoints that skip the same resolve helper

• Upload filenames that smuggle path segments or reserved sidecars

1. One dedicated resolve helper per feature root (example: sync-root only for FileSync manager). Do not reuse a looser picker jail for CRUD.

2. Normalize then T383838realpath. Success paths must equal the root or start with T383838root + sep.

3. Fail closed: generic error, HTTP 400 for bad input, never 500 for jail rejects.

4. Upload: sanitize to basename only. Join under a resolved parent. Cap size.

5. Delete: refuse the root itself. Default to file or empty directory only unless recursive delete is explicit and tested.

6. Skip and refuse mutation of dotfiles and protocol sidecars (for FileSync: T383838.rns-filesync*, T383838.rns-xfer*).

7. Mutating routes stay CSRF-protected HTTP via T383838window.api. No WS mutators for file CRUD.

8. Keep identity-scoped state. Never browse or mutate another identity storage path.

• Adversarial traversal and absolute-path cases with bait files that must survive

• Cross-identity bait directory in the same test

• Symlink-out cases (POSIX) for list, read, write, delete

• Oracle or Hypothesis: accept only when resolved path stays under the root

• Frontend mutators go through T383838window.api (apiFetchGuard stays green)

Full workflow: T383838docs/agents/skills/path-jail-local-fs/SKILL.md.

Reference implementation: T383838meshchatx/src/backend/rns_filesync_handler.py (T383838_resolve_manager_path and manager APIs).

Oracle examples: T383838tests/backend/test_rns_filesync_security.py, T383838tests/backend/test_path_jail_oracles.py.